home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / share / doc / python-lazr-uri / README.txt < prev   
Text File  |  2009-03-20  |  4KB  |  150 lines
  1. ..
  2.     This file is part of lazr.uri.
  3.  
  4.     lazr.uri is free software: you can redistribute it and/or modify it
  5.     under the terms of the GNU Lesser General Public License as published by
  6.     the Free Software Foundation, version 3 of the License.
  7.  
  8.     lazr.uri is distributed in the hope that it will be useful, but
  9.     WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  10.     or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  11.     License for more details.
  12.  
  13.     You should have received a copy of the GNU Lesser General Public License
  14.     along with lazr.uri.  If not, see <http://www.gnu.org/licenses/>.
  15.  
  16. lazr.uri
  17. ********
  18.  
  19. The lazr.uri package includes code for parsing and dealing with URIs.
  20.  
  21.     >>> import lazr.uri
  22.     >>> print 'VERSION:', lazr.uri.__version__
  23.     VERSION: ...
  24.  
  25. =============
  26. The URI class
  27. =============
  28.  
  29.     >>> from lazr.uri import URI
  30.     >>> uri1 = URI('http://localhost/foo/bar?123')
  31.     >>> uri2 = URI('http://localhost/foo/bar/baz')
  32.     >>> uri1.contains(uri2)
  33.     True
  34.  
  35. These next two are equivalent, so the answer should be True, even through
  36. the "outside" one is shorter than the "inside" one.
  37.  
  38.     >>> uri1 = URI('http://localhost/foo/bar/')
  39.     >>> uri2 = URI('http://localhost/foo/bar')
  40.     >>> uri1.contains(uri2)
  41.     True
  42.  
  43. The next two are exactly the same.  We consider a url to be inside itself.
  44.  
  45.     >>> uri1 = URI('http://localhost/foo/bar/')
  46.     >>> uri2 = URI('http://localhost/foo/bar/')
  47.     >>> uri1.contains(uri2)
  48.     True
  49.  
  50. In the next case, the string of url2 starts with the string of url1.  But,
  51. because url2 continues within the same path step, url2 is not inside url1.
  52.  
  53.     >>> uri1 = URI('http://localhost/foo/ba')
  54.     >>> uri2 = URI('http://localhost/foo/bar')
  55.     >>> uri1.contains(uri2)
  56.     False
  57.  
  58. Here, url2 is url1 plus an extra path step.  So, url2 is inside url1.
  59.  
  60.     >>> uri1 = URI('http://localhost/foo/bar/')
  61.     >>> uri2 = URI('http://localhost/foo/bar/baz')
  62.     >>> uri1.contains(uri2)
  63.     True
  64.  
  65. Once the URI is parsed, its parts are accessible.
  66.  
  67.     >>> uri = URI('https://fish.tree:8666/blee/blah')
  68.     >>> uri.scheme
  69.     'https'
  70.     >>> uri.host
  71.     'fish.tree'
  72.     >>> uri.port
  73.     '8666'
  74.     >>> uri.authority
  75.     'fish.tree:8666'
  76.     >>> uri.path
  77.     '/blee/blah'
  78.  
  79.     >>> uri = URI('https://localhost/blee/blah')
  80.     >>> uri.scheme
  81.     'https'
  82.     >>> uri.host
  83.     'localhost'
  84.     >>> uri.port is None
  85.     True
  86.     >>> uri.authority
  87.     'localhost'
  88.     >>> uri.path
  89.     '/blee/blah'
  90.  
  91. The grammar from RFC 3986 does not allow for square brackets in the
  92. query component, but Section 3.4 does say how such delimeter
  93. characters should be handled if found in the component.
  94.  
  95.     >>> uri = URI('http://www.apple.com/store?delivery=[slow]#horse+cart')
  96.     >>> uri.scheme
  97.     'http'
  98.     >>> uri.host
  99.     'www.apple.com'
  100.     >>> uri.port is None
  101.     True
  102.     >>> uri.path
  103.     '/store'
  104.     >>> uri.query
  105.     'delivery=[slow]'
  106.     >>> uri.fragment
  107.     'horse+cart'
  108.  
  109. ====================
  110. Finding URIs in Text
  111. ====================
  112.  
  113. lazr.uri also knows how to retrieve a list of URIs from a block of
  114. text.  This is intended for uses like finding bug tracker URIs or
  115. similar.
  116.  
  117. The find_uris_in_text() function returns an iterator that yields URI
  118. objects for each URI found in the text.  Note that the returned URIs
  119. have been canonicalised by the URI class:
  120.  
  121.   >>> from lazr.uri import find_uris_in_text
  122.   >>> text = '''
  123.   ... A list of URIs:
  124.   ...  * http://localhost/a/b
  125.   ...  * http://launchpad.net
  126.   ...  * MAILTO:joe@example.com
  127.   ...  * xmpp:fred@example.org
  128.   ...  * http://bazaar.launchpad.net/%7ename12/firefox/foo
  129.   ...  * http://somewhere.in/time?track=[02]#wasted-years
  130.   ... '''
  131.  
  132.   >>> for uri in find_uris_in_text(text):
  133.   ...     print uri
  134.   http://localhost/a/b
  135.   http://launchpad.net/
  136.   mailto:joe@example.com
  137.   xmpp:fred@example.org
  138.   http://bazaar.launchpad.net/~name12/firefox/foo
  139.   http://somewhere.in/time?track=[02]#wasted-years
  140.  
  141. ===============
  142. Other Documents
  143. ===============
  144.  
  145. .. toctree::
  146.    :glob:
  147.  
  148.    *
  149.    docs/*
  150.